# What is Kitty-Visual?

Kitty-visual is a program tha allows for searching and visually selecting text
on the kitty scrollback buffer using the usual vim semantics. 

# Why is Kitty-Visual?

The kitty terminal emulator provides an assortment of features that make it
using a terminal multiplexer, such as tmux, redundant (at least, if you don't
care about attaching and detaching). Alas, it doesn't allow for natively copying
text from the scrollback using the keyboard (a feature that I very much like),
instead, it allows to pipe the scrollback contents to your program of choice.

A perfectly reasonable solution, but, since I dislike the context switching on
such a recurrent action, and the issues surrounding displaying ANSI escape
sequences on any program other than the terminal itself; I opted for a solution
in which the scrollback remains in place.

That was reason number one, the secondary reason was simply a desire to code. I
emphasize this due to the existence of other tools that, likely (since I have
yet to use them), already solves this issue. They can be found on the documentation
for kitty under the section [Scrollback manipulation](https://sw.kovidgoyal.net/kitty/integrations/).

# How it works

Kitty-visual mimics moving around in a read-only text file opened in nvim, the
text in question is whatever the contents from kitty's scrollback. An actual
nvim instance runs on the background doing most of the heavy lifiting. Ideally
it would be *all* of the heavy lifting, but I'm not smart enough to figure out
how to use the UI functions from the nvim API.

# Installation

Firstly, install the msgpack-rpc if you haven't already:

```text
gem install msgpack-rpc
```

Clone this repository and place it somewhere pertinent, it can be anywhere, but
I prefer to put it under in kitty's configuration directory:

```text
cd ~/.config/kitty/
git clone https://notabug.org/paone/kitty-visual.git
```

Then add the following lines in your kitty.conf:

```text
map f5 launch --type=overlay
    \ --stdin-source=@screen_scrollback
    \ --stdin-add-formatting
    \ ~/.config/kitty/kitty-visual/kitty-visual.rb
```

This maps kitty-visual to the F5 key. You can change to whatever key you prefer.
For a more vim-like experience, I make use of the modes functionality in kitty:

```text
map --new-mode normal shift+space
map --mode normal v combine : 
    \ pop_keyboard_mode :
    \ launch --type=overlay
	\ --stdin-source=@screen_scrollback
	\ --stdin-add-formatting
	\ ~/.config/kitty/kitty-visual/kitty-visual.rb
```

Now pressing "shift+space" will put you in insert mode, then you can press "v"
to launch kitty-visual. By default, pressing "Escape" will exit kitty-visual and
put you back the prompt.

# Configuration

Since kitty-visual makes use of nvim on it's backend, your nvim configurations
will be applied normally. Take consideration, thought, that kitty-visual opens
the scrollback in read-only mode and so any mapping that edits text will
silently fail.

If you want to add any configuration to kitty-visual only, merely edit the
kitty-visual.vim file. By default it contains one block that you should leave
alone: 

```text
" ######## DONT'T EDIT THIS BLOCK ########
let startup = '/tmp/.kitty-visual/startup'

fu Send(msg, fifo)
	exec 'redir! >' .. a:fifo
		echo a:msg
	redir END
endf

au VimEnter * call Send('ready', g:startup)
" #######################################
```

And a single mapping:

```text
vnoremap y "+y
```

This line makes pressing "y" while in visual mode, copy the selected text to the
system's clipboard It should, hopefully, make using kitty-visual more intuitive.
